home *** CD-ROM | disk | FTP | other *** search
/ Amiga Inside! / Amiga FD Inside (1995)(Ultramax).iso / berndspd / sonstiges / askenv / docs / askenv.dok < prev    next >
Encoding:
Text File  |  1993-05-29  |  12.5 KB  |  428 lines
  1.  
  2.     AskEnv 2.5                                            23-Mar-93
  3.     ==========
  4.  
  5.  
  6.     Wozu dient AskEnv?
  7.     ------------------
  8.  
  9.  Der einzige Befehl von AmigaDos zur Eingabe von Daten ist der ASK-Befehl.
  10.  Seit der Veröffentlichung von OS2 ist ARexx ein Bestandteil des
  11.  Betriebssystems. Dieser Sprache fehlen aber ebenfalls Befehle für die
  12.  Kommunikation mit dem Benutzer, die über Zeile schreiben und lesen
  13.  hinausgehen. Kein Wunder, denn die Sprache stammt von IBM-Grossrechnern
  14.  mit Zeichenterminals.
  15.  
  16.  Mit AskEnv werden diese Eingabemöglichkeiten erweitert. AskEnv ermöglicht
  17.  ARexx-Programmen, Shell-Scripts, Superbase DML-Programmen und allen anderen
  18.  Sprachen, die ein externes Programm aufrufen und eine Datei einlesen können,
  19.  einen einfachen Aufruf von System-, File- und frei definierbaren Requestern.
  20.  
  21.  AskEnv braucht mindestens OS 2.04.
  22.  
  23.  
  24.     Aufruf:
  25.     -------
  26.  
  27.  Der Programmstart ist nur aus dem CLI sinnvoll (oder ARexx, Superbase...):
  28.  
  29.  AskEnv [EOL/S,F=FREQ/S,DEF/K,SBMODE/S,S=SREQ/K,BODY/K,NEG/K,POS/K,GADFILE/K]
  30.  
  31.  AskEnv ist pure, kann also resident geladen werden.
  32.  
  33.  
  34.  
  35.     Funktionen
  36.     ==========
  37.  
  38.  Es gibt zwei Klassen von Funktionen in Askenv: einfache, bei denen sich
  39.  der Aufwand für die Eingabe auf die Argumente in der Kommandozeile
  40.  beschränkt. Komplexe Funktionen hat es nur eine: mit einem Konfigurations-
  41.  File kann ein frei definierbarer Requester gebastelt werden.
  42.  
  43.  
  44.     einfache Funktionen
  45.     -------------------
  46.  
  47.     Zeile lesen
  48.     -----------
  49.  
  50.     AskEnv [>datei] [EOL]
  51.  
  52.  Im Shell-Fenster wird eine Zeile von der Tastatur gelesen bis zum 
  53.  Zeilenende, der Text wird in die Standardausgabe geschrieben. Mit EOL kann
  54.  bei allen einfachen Funktionen ein Zeilenende an den Text gehängt werden.
  55.  (Mit dieser Funktion fing alles einmal an!)
  56.  
  57.  
  58.     File-Requester
  59.     --------------
  60.  
  61.     AskEnv [>datei] FREQ Titel [DEF pfad] [DIR] [SBMODE] [EOL]
  62.  
  63.  ruft einen File-Requester mit "Titel" in der Titelzeile auf. Mit DEF kann 
  64.  ein Pfad zu einer Datei oder Verzeichnis vorgegeben werden. Mit DIR wird der
  65.  Requester auf eine Verzeichnisauswahl beschränkt; Dateien werden dann nicht
  66.  angezeigt.
  67.  
  68.  WARNUNG: Wenn der File Requester von SBPro aus gestartet wird, muss die
  69.  Option SBMODE verwendet werden, sonst hängt der Requester. Dies ist ein Bug
  70.  in SBPro: es mag es gar nicht, wenn man auf sein Fenster zugreift um den
  71.  Screen zu bestimmen, auf dem es läuft.
  72.  
  73.  
  74.      System-Requester
  75.     ----------------
  76.  
  77.     AskEnv SREQ Zeile1 [BODY Zeile2] POS posiKnopf [NEG negaKnopf]
  78.  
  79.  Wird der negative Text gewählt, wird ein Fehlercode WARN zurückgegeben.
  80.  
  81.  
  82.  
  83.     komplexe Requesterfunktionen
  84.     ----------------------------
  85.  
  86.  Mit "AskEnv gadfile <file>" kann eine Beschreibung eines Requesters gelesen
  87.  werden, ein unstrukturiertes ASCII-File mit Schlüsselwörtern. Die Elemente
  88.  können beliebig auf Zeilen verteilt werden.
  89.  
  90.  Strings müssen auf einer Zeile liegen und mit " " einrahmt werden, wenn sie
  91.  Leerzeichen enthalten.
  92.  
  93.  Mit ";" werden Kommentare eingeleitet. Schlüsselwörter müssen gross
  94.  geschrieben werden.
  95.  
  96.  
  97.     IMMEDIATE vs SELECT-Modus
  98.     -------------------------
  99.  
  100.  Askenv wählt sich einen von 2 Modi, abhängig von den definierten Gadgets.
  101.  
  102.     IMMEDIATE     Requester verschwindet nach der ersten Berührung;
  103.             die ID des Gadgets wird in die Variable VAR, die im
  104.             Header genannt wird, geschrieben. Ist kein Name unter
  105.             VAR angegeben, wird die Variable "AskEnv_Button"
  106.             verwendet.
  107.             Die ID des Buttons ist die Nummer in der Reihenfolge
  108.             der Definitionen, beginnend mit 1.
  109.  
  110.     SELECT         bleibt, bis ein END-, CANCEL- oder das Close-Gadget
  111.             gewählt wird. Dann werden die Zustände aller Gadgets
  112.             rausgeschrieben.
  113.  
  114.     In beiden Fällen bewirkt das Close-Gadget einen WARN-Error und
  115.     nichts wird geschrieben. Variablenwerte sind also nicht definiert!
  116.     Meistens bleiben sie auf den vorherigen Werten, die können aber durch
  117.     andere Programme verändert worden sein!
  118.  
  119.  Der Modus wird automatisch ermittelt:
  120.  
  121.     Nur Buttons werden als "IMMEDIATE" behandelt. Wenn Nicht-Buttons
  122.     dazukommen, wird auf "SELECT" geschaltet. Zu den Nicht-Buttons
  123.     gehören auch Buttons mit File-Requester- oder Programmstart-
  124.     Funktionen.
  125.  
  126.     Elemente mit Read-only werden dabei nicht beachtet.
  127.  
  128.  
  129.     Konfigurations-File
  130.     -------------------
  131.  
  132.  Das File besteht aus einem Header und beliebig vielen Gadget-Definitionen.
  133.  
  134.  Im Header stehen die globalen Eigenschaften:
  135.  
  136. WINDOW         : dieses Schlüsselwort muss am Anfang des Files stehen.
  137.  
  138. SIZE x y w h    : durch Spaces getrennt; bin nicht verantwortlich für
  139.           sinnvolle Koordinaten.
  140.  
  141. Als Alternative:
  142.  
  143. CENTER w h    : Zentriert den Requester auf dem Bildschirm.
  144.  
  145. NAME name    : Fenstername, optional
  146.  
  147. SCREEN screen    : screen ist der Name eines Public-Screens, auf dem sich der
  148.           Requester öffnen soll. Ist kein Public-Screen dieses
  149.           Namens vorhanden, wird der Default Public Screen (meist die
  150.           Workbench) verwendet.
  151.  
  152. VAR name    : Im Immediate-Modus, dh. wenn nur Buttons vorhanden sind,
  153.           wird die Nummer des Buttons rausgeschrieben.
  154.  
  155.           Im Select-Modus wird ebenfalls die Nummer des gewählten
  156.           Buttons hier reingeschrieben, dies aber nur, wenn das
  157.           Schlüsselwort GLOBAL dabei steht! GLOBAL kann auch ohne
  158.           Variablenname verwendet werden, es darf dann nur nicht vor
  159.           dem abschliessenden "#" stehen.
  160.  
  161.           Wurde kein Name unter VAR angegeben, so wird in die 
  162.           Variable "AskEnv_Button" geschrieben.
  163.  
  164.  
  165.  Achtung: ab Version 2.4 kann mit VAR keine Datei mit allen Variablen mehr
  166.  erzeugt werden. Das war ein Ueberbleibsel aus frühen Tagen, für das wohl
  167.  kaum mehr Bedarf besteht. Falls erwünscht, kann ich es ja wieder hinein-
  168.  nehmen.
  169.  
  170.  
  171.  Nach dem Header folgen die Gadget-Definitionen:
  172.  
  173.  Ein Gadget beginnt mit einem Schlüsselwort und endet mit " #" (wie die
  174.  MountList).
  175.  Zur Zeit werden folgende Gadget-Typen unterstützt:
  176.  
  177.     BUTTON        in verschiedenen Funktionen
  178.     CHECKBOX
  179.     INTEGER        nur zur Vollständigkeit
  180.     NUMBER        readOnly
  181.     CYCLE
  182.     STRING
  183.     MX
  184.     TEXT        readOnly
  185.  
  186.     HIBOX        hervorstehender Rahmen
  187.     LOBOX        vertiefter Rahmen
  188.  
  189.  Ausserdem können ein Button- und ein String-Gadget zu einem File-Requester-
  190.  Aufruf kombiniert werden und über den Buttontyp Programme aufgerufen
  191.  werden.
  192.  
  193.  
  194.     Funktionen für alle Gadgets:
  195.     ----------------------------
  196.  
  197. POSITION x y w h: obligatorisch für alle. Die minimale Höhe der Gadgets
  198.           richtet sich nach der Höhe des Screenfonts.
  199.  
  200. LABEL text    : Gadgettext, voreingestellt IM Gadget, kann mit...
  201.  
  202. PLACETEXT ort    : noch gesetzt werden: ABOVE, BELOW, LEFT, RIGHT
  203.  
  204. END        : Dieses Gadgets bricht den Requester ab. Kann bei
  205.           mehreren Gadgets eines Fensters verwendet werden.
  206.  
  207. CANCEL        : Abbruch des Requesters. Nichts wird geschrieben.
  208.  
  209. GLOBAL var
  210.  LOCAL var    : in diese entweder lokale oder globale (ENV:) Variable wird
  211.           der Wert dieses Gadgets geschrieben. Was genau geschrieben
  212.           wird, ist vom Typ abhängig.
  213.  
  214. ENTRY        : Falls verwendet, MUSS es am Schluss einer Definition 
  215.           stehen. Danach folgen 1 bis n Einträge, abhängig vom Typ.
  216.  
  217.  
  218.     Spezielles zu den Typen:
  219.     ------------------------
  220.  
  221.     BUTTON
  222.     ------
  223.  
  224.  Zurückgegeben wird im IMMEDIATE-Modus die Nummer des Buttons in der im 
  225.  Header definierten globalen Variable. Nur Buttons und in Reihenfolge der
  226.  Definition abzählen!!
  227.  Im SELECT-Modus wird die Nummer in die Variable "AskEnv_Button" geschrieben,
  228.  aber nur von Buttons, die das Schlüsselwort GLOBAL zusammen mit einer Dummy-
  229.  Variablen enthalten.
  230.  
  231.  
  232.     Spezialfunktionen für BUTTONs:
  233.  
  234. FREQ        : Als nächstes Gadget muss eine String-Gadget-Definition
  235.           folgen, in das ein voreingestellter Pfad mit ENTRY
  236.           geschrieben werden kann. Die Wahl des Buttons aktiviert
  237.           dann einen File-Requester, dessen Auswahl zurück ins
  238.           String-Gadget geschrieben wird.
  239.  
  240. DIR        : Zusatzoption für Filerequester: der Requester wird auf eine
  241.                   Verzeichnisauswahl beschränkt; Dateien werden dann nicht
  242.           angezeigt. Kann bei gewissen ASL-Ersatzrequestern versagen
  243.           (z.B. MFR).
  244.  
  245. SYNCRUN        : Die Zeichenfolge, die diesem Schlüsselwort folgt, wird
  246.           als Programm synchron gestartet. AskEnv schaltet sein
  247.           Fenster solange ab, bis das externe Programm beendet
  248.           worden ist. Enthält das Kommando Argumente oder Optionen,
  249.           die mit Leerzeichen abgetrennt werden, muss der Befehl
  250.           in Anführungszeichen stehen!
  251.  
  252.           Der Returncode des aufgerufenen Programms kann bei synchron
  253.           gestarteten Programmen weiterverwendet werden:
  254.  
  255. WARN limit    : mit einer Zahl limit kann festgelegt werden, bis zu welchen
  256.           Fehlerlevel ohne eine Benachrichtigung des Benutzers fort-
  257.           gefahren werden kann. Ist der Returncode grösser als limit,
  258.           öffnet sich ein Requester mit der Option zum Programm-
  259.           abbruch. AskEnv gibt darauf einen Returncode von 10 weiter.
  260.  
  261. ASYNCRUN    : Wie bei SYNCRUN, nur dass der AskEnv-Requester nach dem 
  262.           Absetzen des Kommandos wieder zur Eingabe bereit ist. Das
  263.           asynchron gestartete Programm ist nun unabhängig von 
  264.           AskEnv.
  265.  
  266. FILE filedef    : Optionales Ausgabefile für das asynchron gestartete 
  267.           Program.
  268.           Z.B. NIL:, RAM:Test oder ein CON-Fenster.
  269.  
  270.  Wird ein externes Programm (synchron oder asynchron) gestartet, werden 
  271.  zuerst die Werte aller Variablen rausgeschrieben. Das aufgestartete Programm
  272.  kann somit bereits auf Eingabewerte zb. in Filerequester-Gadgets zugreifen.
  273.  
  274.  Diese Werte können sofort wieder verwendet werden: SYNCRUN und ASYNCRUN-
  275.  Kommandos dürfen Variablen enthalten. Die Definition
  276.  
  277.     STRING ...
  278.      LOCAL myDir ...
  279.  
  280.     BUTTON ...
  281.     SYNCRUN "dir $myDir"
  282.  
  283.  versucht den Inhalt des Stringgadgets als Verzeichnis zu lesen.
  284.  
  285.  
  286.     CHECKBOX
  287.     --------
  288.  
  289. CHECKED     : das Häkchen wird beim Start eingeschaltet.
  290.  
  291.           Als Funktionswert gibt das Checkbox-Gadget 0 zurück, wenn
  292.           gewählt, sonst -1.
  293.  
  294.  
  295.     INTEGER
  296.     -------
  297.  
  298.  Nach ENTRY kann eine Default-Zahl angegeben werden, die beim Aufruf
  299.  im Integer-Gadget erscheint. Mit "MAXCHARS zahl" kann die maximale Zahl
  300.  der Zeichen, die aufgenommen werden, verändert werden (default 20).
  301.  
  302.  
  303.     NUMBER
  304.     ------
  305.  
  306.  Aehnlich INTEGER, aber Read-Only. Es wird nichts geschrieben.
  307.  Mit NOBOX wird der Rahmen unterdrückt.
  308.  
  309.  
  310.     STRING
  311.     ------
  312.  
  313.  Aehnlich INTEGER, auch mit der Einstellmöglichkeit MAXCHARS (default 80).
  314.  
  315.  
  316.     TEXT
  317.     ----
  318.  
  319.  Analog zu INTEGER --> NUMBER
  320.  
  321.  
  322.     CYCLE
  323.     -----
  324.  
  325.  Alle gewünschten Einträge nach ENTRY auflisten. Rausgeschrieben wird die
  326.  Nummer des zuletzt selektierten Eintrags, beginnend bei 0.
  327.  
  328.  Zur Erinnerung: ENTRY immer an den Schluss einer Gadgetdefinition!!.
  329.  
  330.  
  331.     MX
  332.     --
  333.  
  334.  Dieser Gadget-Typ wird wie ein oben erwähntes CYCLE-Gadget installiert und
  335.  ausgewertet. Zusätzlich gibt es noch die Option
  336.  
  337. SPACING    n    : Zusätzlicher Abstand zwischen den einzelnen Einträgen
  338.  
  339.  
  340.     HIBOX, LOBOX
  341.     ------------
  342.  
  343.  ACHTUNG: kein Endzeichen #, nur die vier Parameter X, Y, Breite, Höhe:
  344.  
  345.     HIBOX
  346.     50 20 100 20
  347.  
  348.  
  349.     Tips und Tricks
  350.     ===============
  351.  
  352. TEXT-Typen werden normalerweise zentriert zur X-Koordinate ausgegeben. Soll
  353. eine Reihe von Texten linksbündig ohne Box angeordnet werden, kann dies
  354. mit einer Breitenangabe von 0 und der Option PLACETEXT RIGHT erreicht werden.
  355.  
  356.  
  357.     Abspann
  358.     =======
  359.  
  360. Im Vertriebsverzeichnis müssen enthalten sein:
  361.  
  362.      LACE (dir)
  363.        About.req                        intro.req
  364.        Offset.req                       Select.req
  365.        Strings.req                      warning.req
  366.      HIRES (dir)
  367.        about.req                        intro.req
  368.        Offset.req                       Select.req
  369.        Strings.req                      Warning.req
  370.   AskEnv
  371.   AskEnv.doc
  372.   AskEnv.dok
  373.   Brief.rexx
  374.   BriefHilfe.req
  375.   Changes.doc
  376.   Changes.dok
  377.   dearc.req
  378.   DeArc.rexx
  379.   LiesMich
  380.   Plotter                          Plotter.info
  381.   PrefMan.rexx
  382.   ReadMe
  383.   Test
  384.  
  385.  
  386.     noch zu tun:
  387.     ------------
  388.  
  389. - AREXX Support
  390.  
  391.  
  392. Danke allen, die sich mit Tips und Tricks beteiligt haben.
  393.  
  394.  
  395. Ab V2.4 ist AskEnv mit MungWall und Enforcer gestestet, was keine grosse
  396. Hürde ist, da AskEnv mit M2Amiga Modula2 programmiert wurde.
  397.  
  398. AskEnv wurde gestestet unter OS 2.04 und OS 2.1.
  399.  
  400.  
  401. Dieses Programm ist frei kopierbar. Das Verzeichnis muss vollständig weiter-
  402. gegeben werden.
  403.  
  404. Die Aufnahme in PD-Serien ist erlaubt unter der Bedingung, dass eine Diskette
  405. für nicht mehr als 5 sFr/DM verkauft wird. Wenn die Diskette, mit der
  406. AskEnv erworben wurde, teurer war, bitte ich um einen Hinweis.
  407.  
  408. Soll AskEnv auf Serien, die mit gedruckten Anleitungen vertrieben werden,
  409. veröffentlicht werden, darf dies nur nach Absprache mit dem Autor getan
  410. werden.
  411.  
  412. Alle Rechte verbleiben beim Programmierer.
  413.  
  414.  
  415.  
  416. Bugreports an:
  417.  
  418. ============================================================================
  419.                               Bengt Giger
  420.                             Schmiedgasse 48
  421.                           CH-8640 Rapperswil
  422.                               Switzerland
  423.                               055/27 98 79
  424.  
  425.   Link-CH1 ++41 (0)61 681 63 60       Aminet: B.GIGER%LINK-CH1 44:8010/408.0
  426.                                   Z-Netz: B.GIGER@LINK-CH1
  427. ============================================================================
  428.